Device Keys

This document describes the format of the key data returned by the TPS Device API Registration and Update endpoints (data objects in the deviceKey element in the response message). Also, the same format should be used by the device for sending keys to the TPS via TPS Device API Registration endpoint.

Device key object can have the following fields:

• keyTypeName - key type name, see the chapter Supported Key Types below
• keyDataFormat - key format, see the chapter Supported key formats below
• algorithm - key algorithm
• keyData - key data, encoded in the format specified by keyDataFormat
• keyIndex - key index, used for key versioning

Supported Key Types

The element keyTypeName describes the key type sent to the device. The following key types are currently in use:

Key class	Key Type Name	Key Algorithm	Supported Key Data Format	Description
Private key	SALT	HMAC-SHA256 or RIDANGO	AES or TR34	Tokenization key used for calculating card PAN token
Private key	IPEK	DUKPT-AES	AES or TR34	DUKPT AES Initial PIN Encryption Key, used for encrypting tap data
Private key	IPEK	DUKPT-TDEA	AES or TR34	DUKPT Triple-DES Initial PIN Encryption Key, used for encrypting tap data
Private key	TMS_SECRET	SECRET	PLAIN	Shared Secret
Public key	TMS_PUBKEY	RSA	EP2PUBKEY	TMS Public Key
Certificate	TMS_CACRT	RSA	X509	TLS Root CA certificate of the TMS
Certificate	TMS_DEVICECERT	RSA	X509	Device TLS Client Certificate

Supported key data formats

The exact key format depends on the value of the element keyDataFormat. It can be one of the following:

Format	keyData field encoding	Description
AES	HEX	Key data is encrypted with the AES encryption
TR34	Plain text	Key data is in TR-34 keyblock format
X509	BASE64	Key data is X.509 data structure in DER format
EP2PUBKEY	HEX	Key data is in EP2 Public Key format
PLAIN	HEX	Key data is not encrypted

Which format is used for sending the key data depends from the key type.

AES

Field keyData contains a HEX-encoded private AES key, encrypted with the device's internal Key Exchange Key AES key using AES-CBC encryption. Field keyIndex contains AES IV (initialization vector) value (if not present, then value 0 should be used)

TR34

The following fields are in use:

Field keyData contains a private key in TR-34 format, see below

The following TR-34 header values are used:

Header field	Value
Key Block Version ID	"B"
Key Usage	"B1" - DUKPT IKEY, "K0" - key encryption or wrapping, "D0" - data encryption, 00" - no specific use
Algorithm	"A" - AES, "T" - TDEA, "H" - HMAC
Mode of use	"B" - encrypt/decrypt, X" - derive, "G" - generate only, "N" - no specific
Exportability	"E"

In case of DUKPT IPEK key TR-34 keyblock contains also an optional header "KS" with the hex encoded Initial KSN value.

TR-34 keyblock is encrypted with the device's Device Key Encryption Key (DKEK-PUB) public key and signed with the Device Key Signing Key Private Key (DKSK-PRIV) private key.

Device should first use its Device Key Signing Key Certificate (DKSK-CERT) for verifying the keyblock signature and then use its Device Key Encryption Key (DKEK-PRIV) for decrypting the private key from the keyblock.

TR-34 private key settings

Key Type Name	Key Algorithm	Key Usage	Algorithm	Mode of use
SALT	AES	00	H	G
IPEK	AES	B1	A	X
IPEK	TDES	B1	T	X

X509

The following fields are in use:

Field keyData contains the certificate in BASE64-encoded DER format (see X.509) and field keyIndex is not used.

EP2PUBKEY

The following fields are in use:

Field keyData contains the public key in HEX-encoded EP2 Public Key format (see the 'EP2 Security Specification, version 8.2', chapter '7.5 Format Public Keys').

PLAIN

Field keyData contains the shared secret in HEX-encoded format and field keyIndex is not used.